*plugin_manager.txt*  A Git submodule-based plugin manager for Vim/Neovim

===============================================================================
CONTENTS                                                *plugin-manager-contents*

    1. Introduction ............................ |plugin-manager-introduction|
    2. Installation ............................ |plugin-manager-installation|
    3. Configuration ........................... |plugin-manager-configuration|
    4. Configuration Management ................ |plugin-manager-config-management|
    5. Commands ................................ |plugin-manager-commands|
    6. Usage Examples .......................... |plugin-manager-examples|
    7. Keyboard Shortcuts ...................... |plugin-manager-shortcuts|
    8. Tips & Tricks ........................... |plugin-manager-tips|
    9. Troubleshooting ......................... |plugin-manager-troubleshooting|
    10. License ................................ |plugin-manager-license|
    11. About .................................. |plugin-manager-about|

===============================================================================
1. INTRODUCTION                                     *plugin-manager-introduction*

PluginManager is a simple but powerful plugin management solution for Vim and
Neovim that uses Git submodules to manage plugins. It follows Vim 8's native
package structure and provides an easy-to-use interface for managing plugins.

Features:
- Native package management without dependencies
- Full Git integration for plugin versioning
- Easy backup and restore functionality
- Support for optional (lazy-loaded) plugins
- Interactive sidebar interface
- Helptags generation
- Compatible with both Vim and Neovim

===============================================================================
2. INSTALLATION                                     *plugin-manager-installation*

Prerequisites:
- Vim 8+ or Neovim
- Git 2.40+

The plugin manager uses Git submodules and Vim 8's native package system. Installation is straightforward:

First, ensure your Vim/Neovim configuration is a Git repository:
>
    # For Vim
    cd ~/.vim
    git init
    
    # For Neovim
    cd ~/.config/nvim
    git init
<
Then, add the plugin manager as a Git submodule:
>
    # For Vim
    git submodule add https://github.com/username/vim-plugin-manager.git ~/.vim/pack/plugins/start/vim-plugin-manager
    
    # For Neovim
    git submodule add https://github.com/username/vim-plugin-manager.git ~/.config/nvim/pack/plugins/start/vim-plugin-manager
<
Finally, generate helptags:
>
    # From command line
    vim -c "helptags ~/.vim/pack/plugins/start/vim-plugin-manager/doc" -c q
    
    # Or from within Vim
    :helptags ~/.vim/pack/plugins/start/vim-plugin-manager/doc
<
The plugin manager will automatically create any necessary directories when you install plugins.

===============================================================================
3. CONFIGURATION                                   *plugin-manager-configuration*

PluginManager works with minimal configuration, but you can customize its
behavior with the following global variables:

*g:plugin_manager_vim_dir*       The directory of your Vim configuration.
                               Default: '~/.vim' or '~/.config/nvim'

*g:plugin_manager_plugins_dir*   The directory where plugins are installed.
                               Default: '~/.vim/pack/plugins'

*g:plugin_manager_start_dir*     Directory for auto-loaded plugins.
                               Default: 'start'

*g:plugin_manager_opt_dir*       Directory for optional (lazy-loaded) plugins.
                               Default: 'opt'

*g:plugin_manager_vimrc_path*    Path to your vimrc file.
                               Default: '~/.vim/vimrc' or '~/.config/nvim/init.vim'

*g:plugin_manager_sidebar_width* Width of the sidebar in columns.
                               Default: 60

*g:plugin_manager_default_git_host* Default git host for short plugin names.
                                  Default: 'github.com'

*g:plugin_manager_fancy_ui*      Whether to use Unicode symbols in UI.
                               Default: has('multi_byte') && &encoding ==# 'utf-8'

*g:plugin_manager_enable_logging* Enable/disable error logging.
                                Default: 1

*g:plugin_manager_max_log_size*  Maximum log file size in KB before rotation.
                               Default: 1024 (1MB)

*g:plugin_manager_log_history_count* Number of log files to keep.
                                   Default: 3

*g:plugin_manager_spinner_style* Style for spinners in async operations.
                               Options: 'dots', 'line', 'circle', 'triangle', 'box'
                               Default: 'dots'

*g:plugin_manager_progress_style* Style for progress bars.
                                Options: 'block', 'simple', 'arrow', 'dot'
                                Default: 'block'

*g:plugin_manager_pull_strategy* Git pull strategy for updates.
                               Options: 'ff-only', 'merge', 'rebase'
                               Default: 'ff-only'

*g:plugin_manager_max_concurrent_jobs* Maximum concurrent async jobs.
                                     Default: 4

===============================================================================
4. CONFIGURATION MANAGEMENT                    *plugin-manager-config-management*

Since the plugin manager uses Git to manage your Vim configuration directory,
it's important to understand how to organize your custom configurations.

CUSTOM PLUGIN CONFIGURATIONS ~

The plugin manager will create directories like `.vim/plugin`, `.vim/ftdetect`,
`.vim/autoload`, etc. for its own functionality. A best practice is to create 
your own configuration files for each plugin you install:

For example:
>
    ~/.vim/plugin/nerdtree_config.vim
    ~/.vim/plugin/fzf_config.vim
    ~/.vim/plugin/fugitive_config.vim
<
These files will be automatically included in backups when using
`:PluginManager backup`. The backup command commits all changes in your Vim 
configuration directory before pushing to remote repositories, ensuring all your
custom configurations, mappings, and settings are properly versioned and backed up.

Examples of custom configuration files:

NERDTree Configuration (~/.vim/plugin/nerdtree_config.vim):
>
    " Custom NERDTree configuration
    let g:NERDTreeShowHidden = 1
    let g:NERDTreeMinimalUI = 1
    let g:NERDTreeIgnore = ['^\.git$', '^\.DS_Store$']
    nnoremap <leader>n :NERDTreeToggle<CR>
<
FZF Configuration (~/.vim/plugin/fzf_config.vim):
>
    " Custom FZF configuration
    let g:fzf_layout = { 'down': '~40%' }
    nnoremap <leader>f :Files<CR>
    nnoremap <leader>b :Buffers<CR>
    nnoremap <leader>g :GFiles<CR>
<
USING .GITIGNORE                             *plugin-manager-gitignore*

To exclude certain files from version control, create a `.gitignore` file:
>
    # Ignore undo history
    undodir/*
    # Ignore swap files
    *.swp
    *.swo
    .*.swp
    .*.swo
    swapdir/*
    # Ignore helptags
    doc/tags
    **/doc/tags
    # Ignore netrw history
    .netrwhist
    # Ignore session files
    session/*
    # Ignore local vimrc files
    .exrc
    .vimrc.local
<
Make sure to commit your `.gitignore` file:
>
    git add .gitignore
    git commit -m "Add .gitignore for Vim configuration"
<
ALTERNATIVE: CUSTOM PLUGIN STRUCTURE         *plugin-manager-custom-structure*

As an alternative, you can create your own plugin structure as a Git submodule:
>
    # Create your custom Vim configuration repository
    mkdir ~/my-vim-config
    cd ~/my-vim-config
    git init

    # Create the standard Vim directory structure
    mkdir -p plugin ftplugin ftdetect syntax autoload doc colors after

    # Add your configurations to the appropriate directories
    touch plugin/mappings.vim
    touch plugin/settings.vim
    touch plugin/plugin_configs.vim

    # Commit your changes
    git add .
    git commit -m "Initial setup of my Vim configuration"

    # Push to your own repository (optional)
    git remote add origin https://github.com/yourusername/my-vim-config.git
    git push -u origin main

    # Now add this as a submodule to your Vim configuration
    # You can use either direct Git command:
    cd ~/.vim
    git submodule add https://github.com/yourusername/my-vim-config.git pack/personal/start/my-vim-config
    
    # Or use PluginManager itself:
    :PluginManager add https://github.com/yourusername/my-vim-config.git {'dir':'my-vim-config'}
<
This approach keeps your personal configurations organized and separate from
the plugin manager and other plugins.

===============================================================================
5. COMMANDS                                           *plugin-manager-commands*

The plugin provides the following commands:

:PluginManager                   Show usage information

:PluginManager add <plugin> [options]
                                Install a new plugin
                                <plugin> can be a URL or 'username/repo'
                                [options] can be a dictionary with these keys:
                                  'dir': custom directory name (default: plugin name)
                                  'load': 'start' or 'opt' (default: 'start')
                                  'branch': git branch to checkout
                                  'tag': git tag to checkout
                                  'exec': command to execute after installation

                                For backward compatibility:
                                PluginManager add <plugin> [modulename] [opt]

:PluginManager add <local_path>    Install a plugin from a local directory
                                The local directory is copied to the plugins 
                                directory, excluding any .git folder if present.

:PluginManager remove <plugin> [-f]
                                Remove a plugin
                                Use -f to force removal without confirmation

:PluginManager list              List all installed plugins

:PluginManager status            Show status of installed plugins

:PluginManager update [plugin]   Update all plugins or a specific one

:PluginManager backup            Backup configuration to git remotes
                                1. Copies your main configuration file (.vimrc or 
                                   init.vim) into your .vim directory
                                2. Commits all changes in your Vim configuration
                                   directory (custom files, mappings, settings) 
                                3. Pushes to configured remote repositories.
                                Note: Changes inside plugin submodules are not
                                included in the backup as they are tracked
                                separately as Git submodules.

:PluginManager restore           Reinstall all plugins from .gitmodules

:PluginManager helptags [plugin] Generate helptags for all or specific plugin

:PluginManager summary           Show a summary of plugin changes

:PluginManager reload [plugin]   Reload a specific plugin or all configuration

:PluginManagerRemote <url>       Add a remote repository for backups

:PluginManagerToggle             Toggle the plugin manager sidebar

:PluginBegin                    Start a plugin declaration block
:Plugin <plugin> [options]      Declare a plugin to install
                                <plugin> can be a URL or 'username/repo'
                                [options] can be a dictionary with these keys:
                                  'dir': custom directory name
                                  'branch': git branch to checkout
                                  'tag': git tag to checkout
                                  'exec': command to execute after installation
                                  'load': 'start' or 'opt' for plugin loading
:PluginEnd                      Process and install all declared plugins

:PluginManagerViewLog           View the error log file
:PluginManagerClearLog          Clear the error log file

===============================================================================
6. USAGE EXAMPLES                                     *plugin-manager-examples*

Install a plugin from GitHub:
>
    :PluginManager add tpope/vim-fugitive
<
Install a plugin with a custom name:
>
    :PluginManager add tpope/vim-surround surround
<
Install an optional (lazy-loaded) plugin:
>
    :PluginManager add junegunn/fzf.vim fzf opt
<
Install a plugin from a custom URL:
>
    :PluginManager add https://gitlab.com/user/repo.git
<
Install a plugin from a local directory:
>
    :PluginManager add ~/projects/my-vim-plugin
<
Install a plugin with custom options:
>
    :PluginManager add tpope/vim-fugitive {'dir':'fugitive', 'load':'start', 'branch':'main'}
<
Install a plugin with a specific tag and run a command:
>
    :PluginManager add junegunn/fzf {'tag':'0.24.0', 'exec':'./install --all'}
<
Update all plugins:
>
    :PluginManager update
<
Update a specific plugin:
>
    :PluginManager update vim-fugitive
<
Remove a plugin:
>
    :PluginManager remove vim-fugitive
<
Force remove a plugin:
>
    :PluginManager remove vim-fugitive -f
<
Add a backup remote:
>
    :PluginManagerRemote https://github.com/username/vim-config.git
<
Reload a specific plugin:
>
    :PluginManager reload vim-fugitive
<
Reload all Vim configuration:
>
    :PluginManager reload
<
Declare multiple plugins at once:
>
    PluginBegin
    Plugin 'tpope/vim-fugitive'
    Plugin 'preservim/nerdtree', {'load': 'opt'}
    Plugin 'tpope/vim-surround'
    Plugin 'junegunn/fzf', {'dir': '~/.fzf', 'exec': './install --all'}
    Plugin 'fatih/vim-go', {'tag': '*'} 
    Plugin 'neoclide/coc.nvim', {'branch': 'release'}
    Plugin '~/projects/my-vim-plugin'  " Local plugin from filesystem
    PluginEnd
<
View the error log:
>
    :PluginManagerViewLog
<
Clear the error log:
>
    :PluginManagerClearLog
<
===============================================================================
7. KEYBOARD SHORTCUTS                                *plugin-manager-shortcuts*

The following keyboard shortcuts are available in the PluginManager sidebar:

q       Close the sidebar
l       List installed plugins
u       Update all plugins
h       Generate helptags for all plugins
s       Show status of submodules
S       Show summary of changes
b       Backup configuration
r       Restore all plugins
R       Reload configuration
?       Show usage information

===============================================================================
8. TIPS & TRICKS                                          *plugin-manager-tips*

Backup Your Configuration:
It's recommended to set up a remote repository and use `:PluginManager backup`
regularly to ensure your configuration is safe. The backup operation will first
copy your main configuration file (.vimrc or init.vim) into your .vim directory,
then commit all files in your Vim configuration directory that aren't excluded by
.gitignore, including your custom plugin configurations, mappings, colorschemes,
syntax files and other personal settings. The only changes not included are those
inside plugin submodules themselves, which are tracked separately in their respective
repositories.

MANAGING SECRETS IN CONFIGURATION                *plugin-manager-secrets*

Never store sensitive information (API keys, GPG keys, tokens, passwords) in 
your versioned configuration files. Instead:

1. Create separate configuration files for secrets:
>
    ~/.vim/plugin/fugitive-secrets.vim
    ~/.vim/plugin/api-secrets.vim
    ~/.vim/plugin/private-settings.vim
<
2. Exclude these files in your `.gitignore`:
>
    # Ignore secret configuration files
    plugin/*-secrets.vim
    plugin/private-*.vim
<
3. Or use a private repository if your entire configuration contains sensitive
   information.

4 .You can also reference external files from your main configuration:
>
    " In your .vimrc
    if filereadable(expand("~/api-secrets.vim"))
      source ~/api-secrets.vim
    endif


Loading Optional Plugins:
Optional plugins installed with the 'opt' parameter can be loaded with:
>
    :packadd plugin-name
<
You can also load them conditionally in your vimrc:
>
    if has('feature')
      packadd plugin-name
    endif
<
Managing Plugin Updates:
When updating plugins, PluginManager will stash any local changes in the plugin
repositories. If you've made custom modifications to plugins, consider using
a different approach like git patches.

Organizing Your Plugin Configuration:
For larger Vim setups, consider organizing your plugin definitions using the declarative
syntax in separate files that you source from your vimrc:
>
    " In your vimrc
    source ~/.vim/plugin/core-plugins.vim
    source ~/.vim/plugin/editing-plugins.vim
    source ~/.vim/plugin/language-plugins.vim
<
Then in each file, use the PluginBegin/End blocks to organize by category:
>
    " ~/.vim/plugin/editing-plugins.vim
    PluginBegin
      Plugin 'tpope/vim-surround'
      Plugin 'tpope/vim-commentary'
      Plugin 'tpope/vim-repeat'
    PluginEnd
<
This keeps your vimrc cleaner and makes it easier to manage plugins by category.

===============================================================================
9. TROUBLESHOOTING                             *plugin-manager-troubleshooting*

Issues with Plugin Installation:
- Make sure your Vim configuration directory is a Git repository
- Check that you have write permissions to the plugin directories
- Verify the plugin URL is correct and accessible
- Run ':PluginManagerViewLog' to see detailed error logs

Plugin Not Loading:
- For 'start' plugins, ensure they're in the correct directory
- For 'opt' plugins, make sure you're using `:packadd` to load them
- Reload your vimrc after installing new plugins

Git-related Errors:
- Most issues are related to Git submodule commands
- Run `:PluginManager status` to check the status of all modules
- Try running `:PluginManager restore` to reinitialize all modules

Windows-specific Issues:
- Ensure Git is correctly installed and in your PATH
- Consider using forward slashes in paths, even on Windows
- For local plugin installation issues, try using a plugin option with explicit path:
  :PluginManager add C:/path/to/plugin {'dir': 'plugin_name'}

Problems with Error Messages:
- Check the error log with ':PluginManagerViewLog'
- Increase verbosity with ':set verbose=1' before running commands
- For async operations, set 'g:plugin_manager_debug_mode = 1' to see more details

Permission Issues:
- On Unix systems, check directory permissions with 'ls -la'
- On Windows, ensure you have write access to the plugin directories
- Try restarting Vim with administrator privileges if needed

===============================================================================
10. LICENSE                                             *plugin-manager-license*

PluginManager is released under the MIT License.
Copyright (c) 2018 - 2025 G.K.E. <gke@6admin.io>

See LICENSE file or plugin header for full license text.

===============================================================================
11. ABOUT                                                *plugin-manager-about*

Maintained by: G.K.E. <gke@6admin.io>
Source: https://github.com/log0u7/vim-plugin-manager
Version: 1.3.5

vim:tw=78:ts=8:ft=help:norl: